Version: JavaScript SDK 7.0.0

Transaction Types

Sale

Sale Method

A sale initiates a transaction with the payment terminal. In its simplest form, you only have to pass the amount and currency as parameters.

Parameters

Parameter	Notes
`amount` Required integer	Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).
`currency` Required string	Currency of the transaction.
`saleOptions` SaleOptions	An object to store the customization options for a sale. This object can be empty if no options are required.
`callback_function` Required string	Callback function to subscribe to the transaction status updates.

Code example

var saleOptions = {
    customerReference: "MyCustomReference",
    tipConfiguration: {
        baseAmount: "100",
        skipEnabled: true,
        enterAmountEnabled: true,
        tipPercentages: [
            1,
            2,
            3,
            5
        ]
    },
    bypassOptions: {
        signatureBypass: true,
        pinBypass: true
    },
    merchantAuth: [
        {
            acquirer: "ACQUIRER",
            mid: "11111",
            tid: "22222",
            mcc: "33333"
        }
    ],
    metadata: {
        metadata1: "data1",
        metadata2: "data2",
        metadata3: "data3",
        metadata4: "data4",
        metadata5: "data5"
    }  
}

let operationStartedResult = handpoint.sale('1000', 'USD', saleOptions, function (stat) {
  console.log('Transaction status received -> '+ stat.message) 
});

let transactionReference = operationStartedResult.transactionReference
let result = await operationStartedResult.transactionResult

Returns

Parameter	Notes
OperationStartedResult	Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).

Sale And Tokenization

SaleAndTokenization Method

A sale operation which also returns a card token. This functionality is not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice.

Parameters

Parameter	Notes
`amount` Required integer	Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).
`currency` Required string	Currency of the transaction.
`saleOptions` Required SaleOptions	An object to store the customization options for a sale. This object can be empty if no options are required.
`callback_function` Required string	Callback function to subscribe to the transaction status updates.

Code example

var saleOptions = {
    customerReference: "MyCustomReference",
    tipConfiguration: {
        baseAmount: "100",
        skipEnabled: true,
        enterAmountEnabled: true,
        tipPercentages: [
            1,
            2,
            3,
            5
        ]
    },
    bypassOptions: {
        signatureBypass: true,
        pinBypass: true
    },
    merchantAuth: [
        {
            acquirer: "ACQUIRER",
            mid: "11111",
            tid: "22222",
            mcc: "33333"
        }
    ],
}

let operationStartedResult = handpoint.saleAndTokenization('1000', 'USD', saleOptions, function (stat) {
  console.log('Transaction status received -> '+ stat.message) 
});

let transactionReference = operationStartedResult.transactionReference
let result = await operationStartedResult.transactionResult

Returns

Parameter	Notes
OperationStartedResult	Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).

Transaction Recovery

StartRecovery Method

The terminal has a transaction recovery loop to automatically send back the pending Transaction Result to the web application in case it becomes unreachable (network issue or other).

For the first 100 seconds after a transaction is completed, a background thread will attempt to deliver the result every 5 seconds. If the web application is still unreachable after the first 100 seconds, the retry loop turns into an exponential increment to the power of 2 (8s-16s-32s etc…).

The recovery loop is reinitialized every time the Handpoint application is restarted on the payment terminal or the startRecovery method is triggered.The Transaction Result received through the transaction recovery loop will have the recoveredTransaction field set to true.

Important information: The web application must be successfully connected to a terminal in order to receive the pending transactions.

Code example

//Start recovery of pending transactions 
Handpoint.startRecovery();

Returns

Parameter	Notes
Promise Successful Response	The event has been sent to the payment terminal.
Promise Error Response	The event was not sent to the payment terminal because it is unreachable.

Sale Reversal

SaleReversal Method

A sale Reversal, also called sale VOID allows the merchant to reverse a previous sale operation. This operation reverts (if possible) a specific sale identified with a transaction id. In its simplest form, you only have to pass the amount, currency and originalTransactionID as parameters

Parameters

Parameter	Notes
`amount` Required integer	Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).
`currency` Required string	Currency of the transaction.
`originalTransactionID` Required string	The transaction id of the original sale authorization.
`merchantAuthOptions` MerchantAuthOptions	An object to store the customization options for a saleReversal operation. This object can be empty if no options are required.
`callback_function` Required string	Callback function to subscribe to the transaction status updates.

Code example

var saleReversalOptions = {
    customerReference: "MyCustomReference",
    merchantAuth: [
        {
            acquirer: "ACQUIRER",
            mid: "11111",
            tid: "22222",
            mcc: "33333"
        }
    ],
}

let operationStartedResult = handpoint.saleReversal('1000', 'USD', 'OriginalSaleGUID', saleReversalOptions, CallbackFunction(stat){...});

let transactionReference = operationStartedResult.transactionReference
let result = await operationStartedResult.transactionResult

Returns

Parameter	Notes
OperationStartedResult	Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).

Refund

Refund Method

A refund initiates a transaction with the payment terminal. This operation moves funds from the merchant account to the cardholder´s credit card. In its simplest form, you only have to pass the amount and currency as parameters. For Interac (Canadian Debit Network), refunds can only be processed until Interac closes the batch of transactions at night.

Parameters

Parameter	Notes
`amount` Required integer	Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).
`currency` Required string	Currency of the transaction.
`originalTransactionID` string	The transaction id of the original sale authorization.
`refundOptions` RefundOptions	An object to store the customization options for a refund. This object can be empty if no options are required.
`callback_function` Required string	Callback function to subscribe to the transaction status updates.

Code example

var refundOptions = {
    customerReference: "MyCustomReference",
    bypassOptions: {
        signatureBypass: true,
        pinBypass: true
    },
    merchantAuth: [
        {
            acquirer: "ACQUIRER",
            mid: "11111",
            tid: "22222",
            mcc: "33333"
        }
    ],
}

let operationStartedResult = handpoint.refund('1000', 'USD', undefined ,refundOptions, CallbackFunction(stat){...});

let transactionReference = operationStartedResult.transactionReference
let result = await operationStartedResult.transactionResult

// Linked Refund
handpoint.refund('1000', 'USD', 'OriginalSaleGUID' ,refundOptions, CallbackFunction(stat){...});

Returns

Parameter	Notes
OperationStartedResult	Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).

Refund Reversal

RefundReversal Method

A Refund Reversal, also called Refund VOID, allows the merchant to reverse a previous refund operation. This operation reverts (if possible) a specific refund identified with a transaction id. In its simplest form, you only have to pass the amount, currency and originalTransactionID as parameters.

Parameters

Parameter	Notes
`amount` Required integer	Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).
`currency` Required string	Currency of the transaction.
`originalTransactionID` Required string	The transaction id of the original refund authorization.
`merchantAuthOptions` MerchantAuthOptions	An object to store the customization options for a refundReversal operation. This object can be empty if no options are required.
`callback_function` Required string	Callback function to subscribe to the transaction status updates.

Code example

var refundReversalOptions = {
    customerReference: "MyCustomReference",
    merchantAuth: [
        {
            acquirer: "ACQUIRER",
            mid: "11111",
            tid: "22222",
            mcc: "33333"
        }
    ],
}

let operationStartedResult = handpoint.refundReversal('1000', 'USD', 'OriginalRefundGUID', refundReversalOptions, CallbackFunction(stat){...});

let transactionReference = operationStartedResult.transactionReference
let result = await operationStartedResult.transactionResult

Returns

Parameter	Notes
OperationStartedResult	Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).

MoTo Sale

moToSale Method

Mail Order /Telephone Order (MOTO) sale. MOTO is a type of card-not-present (CNP) transaction in which services are paid and delivered via telephone, mail, fax, or internet communication. Triggering this function will prompt a card input form on the terminal for the merchant to enter the card number, expiry date and CVV of the card to be charged. MOTO has become synonymous with any financial transaction where the entity taking payment does not physically see the card used to make the purchase.

Parameters

Parameter	Notes
`amount` Required integer	Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).
`currency` Required string	Currency of the transaction.
`options` Options	An object to store the customization options for a MOTO sale. This object can be empty if no options are required.
`callback_function` Required string	Callback function to subscribe to the transaction status updates.

Code example

var saleOptions = { 
        customerReference: "MyCustomReference",
    }

let operationStartedResult = handpoint.moToSale('1000', 'USD', saleOptions, function (stat) {
  console.log('Transaction status received -> '+ stat.message) 
});

let transactionReference = operationStartedResult.transactionReference
let result = await operationStartedResult.transactionResult

Returns

Parameter	Notes
OperationStartedResult	Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).

MoTo Refund

moToRefund Method

A MOTO refund operation moves funds from the merchant account to the cardholder´s credit card. In it's simplest form you only have to pass the amount and currency but it also accepts the original transaction id. Triggering this function will prompt a card input form on the terminal for the merchant to enter the card number, expiry date and CVV of the card to be charged. MOTO Refund is a type of card-not-present (CNP) transaction in which services are refunded via telephone, mail, fax, or internet communication. MOTO has become synonymous with any financial transaction where the entity taking payment does not physically see the card used to make the purchase or refund.

Parameters

Parameter	Notes
`amount` Required integer	Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).
`currency` Required string	Currency of the transaction.
`originalTransactionID` string	If this field is populated, it links the refund with a previous sale and effectively limits the maximum amount refunded to that of the original transaction.
`options` Options	An object to store the customization options for a MOTO refund. This object can be empty if no options are required.
`callback_function` Required string	Callback function to subscribe to the transaction status updates.

Code example

var refundOptions = {
    customerReference: "MyCustomReference"
}

let operationStartedResult = handpoint.moToRefund('1000', 'USD', undefined ,refundOptions, CallbackFunction(stat){...});

// Linked Refund
Handpoint.moToRefund('1000', 'USD', '00000000-0000-0000-0000-000000000000' ,refundOptions, CallbackFunction(stat){...});

Returns

Parameter	Notes
OperationStartedResult	Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).

MoTo Reversal

moToReversal Method

A MOTO reversal, also called VOID allows the user to reverse a previous MOTO sale/refund operation. This operation reverts (if possible) a specific operation identified with a transaction id. Note that transactions can only be reversed within a 24 hours timeframe or until the daily batch of transactions has been sent for submission. MOTO Reversal is a type of card-not-present (CNP) transaction used to reverse a previous MOTO Sale or MOTO Refund.

Parameters

Parameter	Notes
`originalTransactionID` Required string	The transaction id of the original sale or refund authorization.
`options` Options	An object to store the customization options for a MOTO reversal operation. This object can be empty if no options are required.
`callback_function` Required string	Callback function to subscribe to the transaction status updates.

Code example

var moToReversalOptions = {
    customerReference: "MyCustomReference"
}

let operationStartedResult = handpoint.moToReversal('00000000-0000-0000-0000-000000000000', moToReversalOptions, CallbackFunction(stat){...});

Returns

Parameter	Notes
OperationStartedResult	Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).

Tip Adjustment

TipAdjustment

A tip adjustment operation allows merchants to adjust the tip amount of a sale or a pre-auth capture transaction before the batch of transactions is settled by the processor at the end of the day. Note: This functionality is only available for the restaurant industry in the United States and the processors currently supporting this functionality are TSYS and WORLDPAY/VANTIV.

Parameters

Parameter	Notes
`tipAmount` Required BigInteger	Tip amount - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
`originalTransactionID` Required String	Transaction id of the original transaction

Code example

handpoint.tipAdjustment('100', '00000000-0000-0000-0000-000000000000') {
});

Returns

Parameter	Notes
Status Message	`Tip adjusted` message for OK `ERROR` message for NOK

Tokenize Card

TokenizeCard Method

Returns a card token (representing the card number). This functionality is not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice.

Parameters

Parameter	Notes
`options` Options	An object to store the customization options for a tokenizeCard operation. This object can be empty if no options are required.
`callback_function` Required string	Callback function to subscribe to the transaction status updates.

Code example

var options = {
    customerReference: "MyCustomReference",
}

Handpoint.tokenizeCard(options, CallbackFunction(stat){...});

Returns

Parameter	Notes
Tokenize Card Response	Transaction Result Object

Card Pan

CardPan Method

A cardPan request will return the full PAN of the card being swiped, dipped or tapped. Only the PANs of whitelisted card ranges will be returned by the Handpoint systems. This operation is mostly used to be able to process funds or points from loyalty cards.

Parameters

Parameter	Notes
`options` Options	An object to store the customization options for a cardPan operation. This object can be empty if no options are required.
`callback_function` Required string	Callback function to subscribe to the transaction status updates.

Code example

var options = {
    customerReference: "MyCustomReference",
}

Handpoint.tokenizeCard(options, CallbackFunction(stat){...});

Returns

Parameter	Notes
Card Pan Response	Transaction Result Object

Transaction Types

Sale​

Sale And Tokenization​

Transaction Recovery​

Sale Reversal​

Refund​

Refund Reversal​

MoTo Sale​

MoTo Refund​

MoTo Reversal​

Tip Adjustment​

Tokenize Card​

Card Pan​

Sale

Sale And Tokenization

Transaction Recovery

Sale Reversal

Refund

Refund Reversal

MoTo Sale

MoTo Refund

MoTo Reversal

Tip Adjustment

Tokenize Card

Card Pan